========
 README
========

What's here
===========

``README``

    This file.

``compile.sh``

    The script that compiles into a bunch of static web pages in a 
    web root directory ``compiled_site``.

``testhttpserver.py``

    A "webserver" that you can run locally that's set up to test a 
    compiled site.

``site``

    The source files for building the web-site.

    ``config.py``

        PyBlosxom configuration file.

    ``flavours``

        Holds the templates for how things get rendered.

    ``plugins``

        Holds the PyBlosxom plugins that are being used by this site.

    ``entries``

        Holds blog entry content.

    ``pages``

        Holds content that's not part of the blog.

    ``static``

        Holds images, javascript, css, fonts, and other things.

    ``blog.ini`` and ``pyblosxom.cgi``

        Miscellaneous PyBlosxom files.

``htaccess``

    This is the htaccess file for the site.  Generally, lave it alone if
    you don't know what it is.  We're currently using it for doing the
    HTTP redirects between the old site's pages and the new site's pages.


Writing a new entry
===================

A blog entry consists of a single file in ``site/entries/news/``.

Each blog entry is a separate file.  The file name extension dictates how
the file is parsed.  Files ending in ``.rst`` are parsed as Restructured
Text and files ending in ``.html`` are in HTML.

The structure of the file goes like this:

* first line is the title of the blog entry
* then zero or more lines of metadata
* then the blog entry body

Here's a template to use::

    <title>
    #published <yyyy-mm-dd HH:MM>
    #author <your name>

    <body of the entry>

See other entries for examples.


Workflow
========

1. Make changes to the site which could be anything from adding a new
   blog entry, to adding a new page, to changing the configuration, to
   changing the templates.

2. Run the ``compile.sh`` script.

3. Test the changes you made to the site by running::

       python testhttpserver.py

   and viewing the site locally in your browser.

4. When everything is fine, commit your changes and push them to the
   server.  The mediagoblin.org site updates every hour.


Compile script requirements
===========================

The site is built with PyBlosxom.  Thus you need to have PyBlosxom installed.

There are a couple of ways to do this: site-wide or in a virtual environment.


Site-wide
---------

Using an administrative account, install PyBlosxom.  Depending on your
system, it could be something like::

    sudo pip install pyblosxom


If you don't have pip, but you do have easy_install, then do::

    sudo easy_install pyblosxom


If you don't have pip or easy_install, then install one of them.

Instructions for pip are at http://www.pip-installer.org/en/latest/index.html .

Instructions for easy_install are at http://pypi.python.org/pypi/setuptools .


virtual environment
-------------------

Set up a virtual environment using `virtualenv
<http://pypi.python.org/pypi/virtualenv>`_.  Then install PyBlosxom into that.
When you go to use the compile script, make sure to put the bin directory early
in the path.

For example, if my virtual environment was in ``/home/willg/venvs/pyblosxom``,
then I would run ``comile.sh`` like this::

    PATH=/home/willg/venvs/pyblosxom/bin:$PATH ./compile.sh


Problems
========

This README is pretty sparse, so if you have problems you should look at
the PyBlosxom documentation at http://pyblosxom.bluesock.org/ and/or talk
to Will.
